%% ------------------------------------------------------------------------
%% Copyright (C) 2021-2024 SJTUG
%% 
%% Licensed under the Apache License, Version 2.0 (the "License");
%% you may not use this file except in compliance with the License.
%% You may obtain a copy of the License at
%% 
%%     http://www.apache.org/licenses/LICENSE-2.0
%% 
%% Unless required by applicable law or agreed to in writing, software
%% distributed under the License is distributed on an "AS IS" BASIS,
%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
%% See the License for the specific language governing permissions and
%% limitations under the License.
%% ------------------------------------------------------------------------

\ProvidesFile{sjtubeamer.tex}[2024/12/21 v3.1.1 User Manual for sjtubeamer (Chinese)]
\documentclass[
    UTF8,
    heading=true,
    12pt,
    a4paper
]{ctexrep}

\pagestyle{plain}

\usepackage{tocloft}
\setlength\cftbeforechapskip{0em}
\renewcommand{\cftchapleader}{
  \cftdotfill{\cftdotsep}}

\usepackage{pifont}

\ctexset{
  part = {
    format = \bfseries\Huge,
    name = ,
    nameformat = \Huge
  },
  chapter = {
    beforeskip = 0pt,
    fixskip = true,
    format = \bfseries,
    name = ,
    nameformat = \hfill\huge,
    number = \arabic{chapter},
    aftername = \,\par\hfill,
    titleformat = \LARGE,
    aftertitle = \par\bigskip\nointerlineskip
		 \rule{\linewidth}{2bp}\par
  },
  section = {
    format = \bfseries\large\raggedright,
	  number = \raisebox{-.1ex}
    {\ding{\numexpr181 + \arabic{section}}},
    numberformat = \Large
  }
}

\usepackage[colorlinks]{hyperref}

\usepackage{enumitem}
\setlist[enumerate]{itemsep=0pt, left=\parindent,
label=\raisebox{-.1ex}{\large\ding{\numexpr171 +
\arabic*}}}
\newenvironment{commentlist}
{\begin{enumerate}\small}
{\end{enumerate}}

\usepackage{tcolorbox}
\newtcbox{\xbutton}[1][red]{on line, arc=3pt,
colback=#1!50!black, colframe=#1!50!black, before
upper={\rule[-3pt]{0pt}{10pt}}, boxrule=1pt,
boxsep=0pt, left=6pt, right=6pt, top=2pt,
bottom=0pt, fontupper=\sffamily, colupper=white}

\usepackage{fontawesome5}
\usepackage{hologo}

\tcbuselibrary{listingsutf8}
\lstset{
    language=[LaTeX]TeX,
    basicstyle=\ttfamily,
    columns=flexible, 
    emph=[1]{usetheme},
    emphstyle=\color{blue},
    extendedchars=false,
    lineskip=-.1cm,
    breaklines
}
\newcommand{\cmd}[1]{\textbackslash{}\texttt{#1}}
\newcommand{\cls}[1]{\texttt{#1}}
\newcommand{\env}[1]{\texttt{#1}}
\newcommand{\pkg}[1]{\texttt{#1}}
\newcommand{\opt}[1]{\texttt{#1}}

\tcbuselibrary{skins,raster}
\newtcbinputlisting[auto counter]
{\beamerdemo}[2][1]{
    enhanced jigsaw,
    lower separated=false,
    leftlower=0pt,rightlower=0pt,middle=0pt,
    listing side comment,
    listing file={tutorial/#2},
    listing options={
      style=tcblatex,
      texcsstyle=*\color{red!70!black}
    },
    pdf comment,
    comment style={
      drop lifted shadow,
      graphics pages={#1},
      raster columns=1
    },
    tile,
    title={\faEdit 示例 \thetcbcounter}
}

\newtcbinputlisting{\examplecode}[1]{
  listing file={tutorial/#1},
  listing only,
  enhanced jigsaw,
  lower separated=false,
  leftlower=0pt,rightlower=0pt,middle=0pt,
  listing options={
    style=tcblatex,
    texcsstyle=*\color{red!70!black}
  },
  tile,
  title={\faEdit 样例 #1}
}

\newenvironment{beamerdemoraster}[3][]{
    \begin{tcbraster}[
      raster columns=3, colframe=#2,
      colback=white, colbacktitle=#2!50!white,
      fonttitle=\small\bfseries\ttfamily,
      fontupper=\ttfamily, left=0pt, right=0pt,
      top=0pt, bottom=0pt, boxsep=0pt,
      boxrule=0.6pt, toptitle=1mm,
      bottomtitle=1mm, drop lifted shadow,
      center title, graphics pages={#1}]
      \tcbincludepdf{tutorial/#3}
    \end{tcbraster}
}{}

\usepackage{array}

\usepackage{sjtuvi}

\newcommand{\testclr}[1]{\fcolorbox{black}{#1}{\phantom{XX}} \texttt{#1}}

\def\themename{\textsf{SJTUBeamer}}

\def\sjtuglogo{
  \parbox{4cm}{
    \centering
    \includegraphics[width=4cm]{sjtug.pdf}\\
    \vspace*{5pt}
    \includegraphics[width=3cm]{sjtug_text.pdf}
  }
}

\begin{document}
\title{\themename}
\date{\today}

\begin{titlepage}
  \setlength{\parindent}{0em} \bfseries\sffamily
  \begin{tikzpicture}[remember picture, overlay]
    \fill[sjtuRedPrimary] (current page.south west)
    rectangle (current page.north east);
  \end{tikzpicture}
  \color{white}\vfill

  \Huge\themename{} 用户手册

  \Large\LaTeX{} Beamer 幻灯片模板

  \vfill
  \resizebox{!}{2cm}
  {\secondaryinstlogo{
      \resizebox{!}{0.95cm}
      {\includegraphics{sjtug.pdf}}
    }{\sjtubadge{}}}

  \vfill

  \hskip-6em\resizebox{\paperwidth}{!}{\sjtugate[white]}
\end{titlepage}

\chapter*{\themename{} 介绍}

\themename{} 是基于 \cls{beamer} 文档类的主题宏集。

\section*{何时应该使用这个主题？}
众所周知，\LaTeX\ 是一种非常专业的排版语言，其中 \cls{beamer} 宏包是为了方便
\LaTeX{} 用户制作幻灯片而创造的宏包。为了获得专业的幻灯片文档，下面是一些使用
\cls{beamer} 的时机：
\begin{enumerate}
  \item 重要正式的学术场合。
  \item 大型文档的构建（上百页）。
  \item 已经使用 \LaTeX{} 写好稿子，需要基于此演说。
\end{enumerate}

而 \themename{} 为上海交通大学的 \LaTeX{}
用户提供了一些内置功能，以快速构建交大主题的幻灯片文档。

\section*{何时不应该使用这个主题？}
然而 \LaTeX{} 不是可见即可得的，编译需要花费时间，学习 \LaTeX{}
也需要花费时间。下面是一些不推荐使用的情况：
\begin{enumerate}
  \item 幻灯片需要大量的美术，图形需要大量的动画。纵然 \LaTeX{}
        支持矢量图的绘制，但是需要的编译时间也会成倍的增长，Ti\emph{k}Z
        绘图更偏重于计算图形绘制。
  \item 文档较小，或者公式很少。这种情况使用 \cls{beamer}
        略显多余，造轮子花费的时间可能不够划算。
\end{enumerate}

遇到任何使用问题，欢迎前往
\href{https://github.com/sjtug/SJTUBeamer/discussions}
{Discussions} 参与讨论。并推荐附上本文档一直采用的最小工作集示例方式。

\setcounter{tocdepth}{0}
\tableofcontents

\part{基础操作}
\chapter{安装}

\section{运行环境}

为了使用 \themename{} 的全部功能，请使用下者之一：
\begin{enumerate}
  \item \href{https://mirrors.sjtug.sjtu.edu.cn/ctan/systems/win32/miktex/setup/windows-x64/}{MiK\TeX{}}
  \item \href{https://mirrors.sjtug.sjtu.edu.cn/ctan/systems/texlive/Images/}
        {\TeX{} Live} 或
        \href{https://mirrors.sjtug.sjtu.edu.cn/ctan/systems/mac/mactex/}
        {Mac\TeX{}} 2019 及以上版本
\end{enumerate}

% 上传至 Overleaf 后添加对应在线步骤
% 上传至 CTAN 后本段可以直接更改为安装宏包的标准流程
\section{下载模板}

\begin{enumerate}
  \item git 用户可以使用
        \begin{verbatim} git clone https://mirror.sjtu.edu.cn/git/SJTUBeamer.git/ \end{verbatim}
        克隆本存储库。
  \item 或者前往 GitHub 上的
        \faGithub{}
        \href{https://github.com/sjtug/SJTUBeamer}{sjtug/SJTUBeamer} 页面，点击
        \xbutton[green]{Code}
        按钮下载压缩文件，在解压后的主目录里新建 \TeX{}
        源文件即可调用该模板。
  \item 或者点击进入存储库侧栏的
        \href{https://github.com/sjtug/SJTUBeamer/releases}{\textsf{Releases}}
        下载查看最新发布版本，并下载 \textsf{Assets} 栏的
        \textsf{sjtubeamer-ctan.zip}。
        将该压缩包中的内容安装到发行版路径中，并
        刷新文件名数据库，即可全局使用。
\end{enumerate}

\section{测试模板}

\begin{enumerate}
  \item[\faApple{} \faLinux] *nix 系统采用
        \hologo{XeLaTeX} 编译以获得中文支持。
  \item[\faWindows] Windows 系统采用
        \hologo{pdfLaTeX} 编译以获得更快的编译速度。
  \item[\faWrench] 也可以直接使用 \textsf{latexmk
          (latexmkrc)} 编译示例的主文档。
\end{enumerate}

下面的代码可以用于测试 \themename{} 是否可以正常使用。

\beamerdemo[1]{step1.tex}

\begin{commentlist}
  \item 第一行载入 \pkg{ctex} 宏包提供的 \cls{ctexbeamer}
  文档类。如果需要使用 16:9 的荧幕比例，可以参照示例 2 的相关参数。也可以添加诸如
  \opt{9pt}, \opt{10pt}, \opt{11pt}, \opt{12pt}
  之类的全局字体大小参数。
  \item 如果不需要中文支持，可以直接使用 \cls{beamer} 文档类。
  \item 第二行载入 \cls{sjtubeamer} 主题。
  \item 使用 \env{document} 环境进入文档主体。
  \item 使用 \env{frame} 环境创建新的幻灯片（帧）。
  \item 在帧中输入文字即可在屏幕垂直居中位置产生文字。
\end{commentlist}

\clearpage

\chapter{样式}

在开始填入内容前，应当首先确定需要使用的样式。\themename{}
目前提供了三种不同的主要主题、两种配色和明暗模式。

\noindent{\ttfamily\hfil\hspace*{-.5cm} + maxplus
  \hfil\hfil\hspace*{-.5cm}  + max \hfil\hfil +
  min
  \hfil}\par
\vspace*{-.2cm}
\begin{beamerdemoraster}
  [1,3,5,2,4,6]{red}{step2tb.pdf}
\end{beamerdemoraster}

\begin{beamerdemoraster}
  [1,2,3]{blue}{step2bd.pdf}
  \marginpar{\ttfamily\raisebox{1.8cm}{+ blue}}
  \marginpar{\ttfamily\raisebox{-1.8cm}{+ light}}
\end{beamerdemoraster}
\vspace*{-.2cm}
\begin{beamerdemoraster}
  [1,2,3]{blue}{step2bl.pdf}
\end{beamerdemoraster}

\clearpage

\themename{} 可以与 \cls{beamer} 提供的九种外样式随意搭配。

\def\myincludepdf#1#2{
  \tcbincludepdf[title={#1},
    colframe=red!50!black, colback=red!10!white,
    colbacktitle=red!50!white,
    left=0pt, right=0pt, top=0pt,
    bottom=0pt, boxsep=0pt, boxrule=0.6pt,
    toptitle=1mm, bottomtitle=1mm, drop lifted
    shadow, center title, fonttitle=\ttfamily]
  {tutorial/#2}
}
\begin{tcbitemize}[
    raster columns=3,
    raster equal height,
    left=0pt, right=0pt, top=0pt,
    bottom=0pt, boxsep=0pt, boxrule=0pt]
  \tcbitem
  \myincludepdf{miniframes}{step2miniframes.pdf}
  \tcbitem
  \myincludepdf{default}{step2default.pdf}
  \tcbitem
  \myincludepdf{infolines}{step2infolines.pdf}
  \tcbitem
  \myincludepdf{smoothbars}{step2smoothbars.pdf}
  \tcbitem
  \myincludepdf{sidebar}{step2sidebar.pdf}
  \tcbitem \myincludepdf{split}{step2split.pdf}
  \tcbitem \myincludepdf{shadow}{step2shadow.pdf}
  \tcbitem \myincludepdf{tree}{step2tree.pdf}
  \tcbitem
  \myincludepdf{smoothtree}{step2smoothtree.pdf}
\end{tcbitemize}

\beamerdemo[1]{step2.tex}

\chapter{草稿}

在确定版式后，下一步就要输入文字填入内容了。
由于 \LaTeX{} 的编译速度较慢，在打草稿的时候，
我们推荐开启 \cls{beamer} 文档类的 \opt{draft} 模式，只关注于内容。
在这种模式下，图片都不会被载入，而是使用一个占位符代替。

\beamerdemo[1]{step3.tex}

\begin{commentlist}
  \item 使用 \env{columns} 环境分栏，也可以采用
  \pkg{multicol} 宏包提供的 \env{multicols} 环境。后者还兼容
  \cls{article} 文档类。
  \item 该模式也会关闭目录与引用的生成。
\end{commentlist}

\clearpage

当然，如果演示文稿的内容过长的话，推荐分成许多个文件编写。最后通过一个主文件拼接起来。
如果暂时想专心编写某一部分的内容，可以直接注释掉其他部分的入口。

\beamerdemo[1]{step4.tex}

\chapter{封面}

当内容完成之后，就可以制作封面和封底了。
在此之前需要先填写该文档的元数据信息：标题、副标题、作者、组织、日期。

\beamerdemo[1,2]{step5.tex}

\begin{commentlist}
  \item 在载入模板时选择 \opt{maxplus}, \opt{max},
  \opt{min} 以使用不同的标题页结尾页模板。
  \item 组织（\cmd{institute}）可选，\opt{min}
  会根据二级机构的处理方法排列徽标。
  \item \cmd{maketitle} 可以制作标题页，\cmd{makebottom}
  可以制作结束页$^*$。
  \item$^*$ 标题页中 \cmd{thanks}
  被禁用，\cmd{makebottom} 是 \themename{} 专有命令。
  \item[\faExclamationTriangle] 将元数据写在
  \env{document} 中可能会产生警告，可无视。
\end{commentlist}

\chapter{目录}

目录功能是 \cls{beamer} 的特色之一。\themename{}
提供了两种插入目录的方法——两种方法也可以共同使用。

\section{单页目录}

传统的插入目录的方法就是使用标准的目录命令，使用 \opt{hideallsubsections}
隐藏所有小节标题。

\beamerdemo[1]{step6+.tex}

\section{节次提示}

而新式的方法是使用 \themename{} 优化后的节次页。
现在节次页也会随主题的不同而有不同的样式。
节次页的编号支持在加载主题之后使用
\cmd{ctexset} 来更改格式，详见
\href{https://mirrors.sjtug.sjtu.edu.cn/CTAN/language/chinese/ctex/ctex.pdf#7}{\CTeX{} 宏集手册}。

\begin{beamerdemoraster}[1,2,3]{red}{step7s.pdf}
\end{beamerdemoraster}

\beamerdemo[4]{step7+.tex}

\begin{commentlist}
  \item \cmd{AtBeginSubsection} 用于指定每小节开始时的动作。
  \item 后文的 \cmd{AtBeginSection} 用于指定每节开始时的动作。
\end{commentlist}

\section{分割部分}

如果内容过多，可以采用 \cmd{part}
将内容分割为多个部分。新建一个部分都会新建一个部分页$^*$。

\beamerdemo[1]{step8+.tex}

\begin{commentlist}
  \item \cmd{part} 在简短的演讲中应当较少使用，
  因为顶部的导航栏会在每一部分开始后重新开始，
  之前的节次目录将会清空。
\end{commentlist}

\section{高亮节次}

使用传统目录也可以在每节开始新建一个目录高亮本节。

\beamerdemo[1]{step9+.tex}

\begin{commentlist}
  \item 如果想要在幻灯片列表环境产生类似的“渐进切换”效果，可以在
  \env{itemize} 环境的每一条后使用 \cmd{pause} 命令。或者是
  \cmd{begin\{itemize\}[<+->]}。
  \item \opt{subsectionstyle} 用于指定小节标题的显示策略，
  三个参数分别代表当前小节、本节中其他小节和其他节的小节该如何显示。
  \opt{show} 将显示，\opt{shaded} 将半显示，\opt{hide}
  将隐藏。在 \themename{} 中推荐设置节目录为
  \begin{verbatim}\tableofcontents[currentsection, subsectionstyle=show/show/hide]\end{verbatim}
  也可以设置 \opt{hideallsubsections}
  以隐藏所有小节标题与目录页保持一致
  \begin{verbatim}\tableofcontents[currentsection, hideallsubsections]\end{verbatim}
  设置小节目录为
  \begin{verbatim}\tableofcontents[currentsection, subsectionstyle=show/shaded/hide]\end{verbatim}
  \item 如果想使用普通的圆形目录结构，在导言区添加
  \begin{verbatim}\setbeamertemplate{sections/subsections in toc}[circle]\end{verbatim}
\end{commentlist}

\chapter{播放}

制作的演示文稿推荐使用 Adobe Acrobat 播放，
浏览器内置的阅读器不支持一些额外功能。
在使用 \cmd{note} 添加幻灯片备注时，推荐使用 Pympress 软件。

\section{Adobe Acrobat}

在 Adobe Acrobat Pro（或免费版本的
\href{https://www.adobe.com/cn/acrobat/pdf-reader.html}{Adobe Acrobat
Reader}）打开演示文稿，在“视图”选单中选择“全屏模式”即可播放。

\begin{figure}[h]
  \centering
  \begin{tcolorbox}[enhanced, title={视图(V)},
    attach boxed title to top left, boxed title
    style={sharp corners}, sharp corners, tile,
    width=6cm]
    \faTv{} 全屏模式(F)\hfill Ctrl+L
  \end{tcolorbox}
\end{figure}

\section{浏览器阅读器}

\begin{enumerate}
  \item[\faChrome] Chrome 浏览器以及 *nix
        内置的阅读器支持“演示”功能。
        \begin{figure}[h]
          \centering
          \begin{tcolorbox}[enhanced,
              title={$\vdots$}, attach boxed
              title to top
              right, boxed title style={
                  circular arc, top=0mm,
                  bottom=2mm,
                  left=3.25mm, right=3.25mm
                },
              sharp corners, tile, width=6cm]
            演示
          \end{tcolorbox}
        \end{figure}
  \item[\faInternetExplorer] Edge
        浏览器需要调整为“适应宽度”\fbox{\faArrowsAltH}，并使用
        \fbox{\sffamily PageDown} 翻页。尽量不要使用该播放方法。
\end{enumerate}

\section{Pympress}
\href{https://github.com/Cimbali/pympress}{Pympress}
是一个类似于 PowerPoint 演示者视图的阅读器。在导言区添加
\begin{verbatim}
\setbeameroption{show notes on second screen}
\end{verbatim}
以展示备注幻灯片（幻灯片内使用 \cmd{note} 标记备注内容）
于每页右侧。使用该软件以自动地识别备注区域展示在演示者屏幕上。

\examplecode{stepdual.tex}

\begin{figure}[h]
  \centering
  \includegraphics[width=0.7\textwidth]
  {tutorial/stepdual.pdf}\\
  放映视图\hspace{6em}演示者视图
\end{figure}

\begin{commentlist}
  \item 如果在使用该选项时通过 \hologo{XeLaTeX} 编译出现问题，请使用
  \hologo{LuaLaTeX} 或 \hologo{pdfLaTeX} 编译。
\end{commentlist}

\part{进阶操作}

\chapter{强调}

在 \themename{} 中有多种强调内容的方法。

\section{文字强调}

主要有两种类型：改变字体和提供高对比。

\beamerdemo[1]{step10.tex}

\begin{commentlist}
  \item \cmd{alert} 会改变文字颜色为主题色。\cmd{emph}
  会将英文字体变为斜体。
  \item \cmd{paragraph} 和 \cmd{highlight}
  都会在文字底部添加纯色方块$^*$，区别在于后者可以设置背景颜色。
  \item \cmd{stamptext} 可以用于生成以印记形为底的高亮小块$^*$，
  需要将高亮的文字数目控制在一个中文字或两个英文字。
\end{commentlist}

\section{区块强调}

也有两种类型：纯色方块和边缘描边。

\beamerdemo[1]{step11.tex}

\beamerdemo[1]{step12.tex}

\begin{commentlist}
  \item \env{block}, \env{alertblock},
  \env{exampleblock}
  环境分别可以产生与主题色对应的三种盒子。
  \opt{min} 主题的盒子非圆角$^*$。
  \item \env{stampbox}
  环境可以产生印记边框盒子$^*$，可以丰富视觉效果与统一视觉形象。
  可接受一个可选参数如 \opt{[sjtuBluePrimary]} 产生其他颜色的边框。
\end{commentlist}

\themename{} 也提供了印记区块环境。

\beamerdemo[1]{step13.tex}

\begin{commentlist}
  \item \env{stampblock}
  用于生成印记区块环境，可以通过可选参数指定编号内容，可选参数缺省时为递增编号。
  该环境可以与 \env{columns} 配合使用，顶端对齐两列对比两种内容。
  \item 必要时也可以在可选参数前添加覆盖参数，例如
  \verb"<1>[1]{标题}"。此时请指定可选参数编号内容
  \verb"[1]"，否则覆盖帧内的区块编号也会意料外地递增。
  \item 如果需要每帧开始从 1 开始计数，可以在导言区添加
  \begin{verbatim}
\AtBeginEnvironment{frame}{\setcounter{stampblockcnt}{0}}
  \end{verbatim}
\end{commentlist}

\clearpage

\themename{} 也提供了水平分割线命令，可以重写上面的例子。

\beamerdemo[1]{step14.tex}

\begin{commentlist}
  \item \cmd{stamphrule} 用来生成一个水平印记分割线，类似于
  \cmd{hrule}。可以添加可选参数用于指定分割线颜色，如
  \cmd{stamphrule[sjtuBluePrimary]}。
  \item 两个 \env{column} 之间可以使用 \cmd{vrule}
  产生竖直分割线隔开，紧随其后的 \cmd{hfill}
  是必要的，这样这个竖直分割线才能水平居中。
  \item 这里使用了 \cmd{textcolor} 来设置竖直分割线的颜色。
\end{commentlist}

\chapter{代码}

\section{代码抄录}

\themename{} 提供了代码抄录的区块环境。

\beamerdemo[1]{step15.tex}

\begin{commentlist}
  \item \env{codeblock} 提供了带行号的代码抄录环境$^*$，
  第一个可选参数可以用于设置语言与其他抄录选项，
  第二个必选参数可以设置代码块的标题。
  \item 需要清理抄录代码在源文件中的缩进，顶格输入。
  若想高亮某一行$^*$，设置 \verb"escapechar=|" 可选参数后，
  该行开头顶格输入 \verb"|\highlightline|"。
  \item 你也可以直接使用
  \cmd{codeblockinput}[选项]\{标题\}\{文件\}
  用于抄录外部文件$^*$，但请通过 \opt{firstline} 和
  \opt{lastline} 选项控制代码行数。
  \item 直接使用 \pkg{listings} 宏包提供的
  \env{lstlisting} 环境与 \env{lstinputlisting}
  命令依然可行，\themename{} 已经对其进行了一些预先的优化。
  \item[\faExclamationTriangle] 使用代码块的页其
  \env{frame} 环境必须添加 \opt{fragile} 参数。
\end{commentlist}

\section{伪代码}

使用 \pkg{algorithm2e} 宏包编写伪代码。

\begin{figure}[h]
  \centering

  \includegraphics[width=0.4\textwidth]
  {tutorial/stepalgo.pdf}
\end{figure}

\examplecode{stepalgorithm.tex}

\begin{commentlist}
  \item \themename{} 对 \env{algorithm}
  环境的标题在中文环境下进行了汉化$^*$，但是对于 \env{procedure} 和
  \env{function} 则没有。请注意使用 \texttt{H} 参数强制浮动体位置。
  \item 如果算法过长，考虑使用 \cmd{scalebox} 对算法环境进行缩小。
  \item 如果还需要在右侧添加说明，这时请使用 \env{minipage}
  环境创建纵向盒子。
\end{commentlist}

\chapter{引用}

方便地引用文献是 \cls{beamer} 的另一大特色，推荐使用
\href{https://www.jabref.org/}{JabRef}
管理文献。\themename{} 对脚注的处理方式进行了一定的优化。

\section{Biber}

\faApple{} \faLinux{} 如果使用的是 \hologo{XeLaTeX}
编译，可以使用 \pkg{biblatex} 宏包，对于中文引用可以使用
\opt{gb7714-2015} 样式，并采用 \textsc{Biber} 进行引用处理。

\beamerdemo[1]{step16+-.tex}

\begin{commentlist}
  \item 使用 \cmd{footnote} 可以添加脚注。
  \item 使用 \cmd{footfullcite}
  进行脚注引用（\pkg{biblatex} 提供的命令）。
  \item 如果认为 \cmd{footfullcite} 引用过长，可以考虑配合
  \opt{style=gb7714-2015ay} 的著者-出版年制使用标准引用命令
  \cmd{cite}。
\end{commentlist}

\section{Bib\TeX{}}

\faWindows 如果使用的是 \hologo{pdfLaTeX} 编译，需要使用
\pkg{gbt7714} 宏包，并采用老式的 \textsc{Bib\TeX{}}
进行引用处理。

\beamerdemo[2]{step17+_.tex}

\begin{commentlist}
  \item 对帧使用 \verb"allowframebreaks"
  参数可以对过长的内容自动换页。
  \item 可以通过重定义 \cmd{bibfont} 缩小引用条目字号大小。
  \item Bib\TeX{} 的个性化样式并没有 \textsc{Biber} 丰富， 如果可以使用 \hologo{XeLaTeX} 编译的情况下，尽可能使用
  \textsc{Biber}。
\end{commentlist}

\section{手动输入}

为了避免使用额外的文献数据库文件，可以手动输入文献列表。

\beamerdemo[1]{step18+-.tex}

\begin{commentlist}
  \item \LaTeX{} 本身提供了 \env{thebibliography}
  环境，环境的强制参数用于指定排版最长的标签（这里是两位数占位符），配套
  \cmd{bibitem[标签]\{主键\}}，在 \cls{beamer} 中需要辅以
  \cmd{newblock}
  来分隔作者、文章标题、书目与其他内容。这里的主键可以在正文中引用。
  \item 在 \cls{beamer} 中可以通过设定 \opt{bibliography
    item}
  模板为对应预设来更改图标，这里是 \opt{text}
  预设用于排印编号。也可以改为文章图标 \opt{article}，图书图标
  \opt{book}
  或网络图标 \opt{online} 等。
  \item 引入 \env{bibliolist} 环境$^*$以避免使用
  \cmd{bibitem} 命令，对于每一条引用添加对应的
  \cmd{articleitem},
  \cmd{bookitem}, \cmd{onlineitem}
  用于切换不同的图标$^*$，并保持与 \cmd{bibitem}
  相同的用法（除了不能设定引用标签）。
  \item 在 \env{bibliolist} 环境中也可以直接使用 \cmd{item}
  以不使用 \cmd{newblock} 来分割条目中的不同部分，正如
  \textsc{SJTUThesis} 所做的那样。但请不要与上一条中的图标命令混用。
\end{commentlist}

\chapter{图表}

表格与统计图是展示数据最直观的方式，可以采用内建的方式插入风格统一的矢量图表。
\themename{} 对此设定了一些预设。

\section{表格}

考虑到许多专业数据是直接存储在逗号分隔符（\texttt{.csv}）文件中的，便于数据内容的后续
更改，用户可以采用 \pkg{pgfplotstable} 宏包从文件插入表格（中文表格需要使用
\hologo{XeLaTeX} 编译）。

\beamerdemo[1]{step19.tex}

\begin{commentlist}
  \item 需要加载 \pkg{pgfplotstable}
  宏包，表头变为主题色，采用三线表的样式。$^*$
  \item 也可以使用标准表格插入的方法，只是不会有这种优化。可以使用
  \href{https://www.tablesgenerator.com/latex_tables}
  {Table Generator} 生成标准表格代码。
\end{commentlist}

\section{统计图}

\beamerdemo[1]{step20.tex}

\begin{commentlist}
  \item 需要加载 \pkg{pgfplots} 宏包，必要时额外加载
  \pkg{pgfplotstable} 宏包以读取文件数据。可以使用
  \href{https://logcreative.github.io/PGFPlotsEdt/}{PGFPlots 统计绘图编辑器}
  生成上述代码。
\end{commentlist}

\section{缓存}

如果你需要使用较多的 Ti\emph{k}Z 和 \pkg{pgfplots}
插图，可以考虑启用图像缓存，当图像没有被更改时会采用上一次的编译产物。\themename{}
已经保护了一些不必要缓存的元素。

\beamerdemo[1]{step21.tex}

\begin{commentlist}
  \item \themename{} 已经加载了
  \verb"\usetikzlibrary{external}"。
  \item[\faExclamationTriangle] 如果使用的是 Overleaf
  这种在线 \LaTeX{} 编译器，您必须要在主文档内使用
  \verb"\tikzexternalize[prefix=build/]" 命令，并且要在同级目录下新建
  \verb"build/" 文件夹，其中应该还有一个占位文档（比如
  \verb".gitkeep"）。可参见
  \href{https://www.overleaf.com/learn/latex/Questions/I_have_a_lot_of_tikz%2C_matlab2tikz_or_pgfplots_figures%2C_so_I%27m_getting_a_compilation_timeout._Can_I_externalise_my_figures%3F}{相关说明}。
\end{commentlist}

\section{独立编译}

还可以配合 \cls{standalone} 文档类对 Ti\emph{k}Z
文档独立编译，在使用时直接插入。这种方法需要做好一定的项目管理。

% TODO: 以后的开发计划：Smart Diagram
%\chapter{插图}

\part{高级操作}
\chapter{徽标}

\themename{} 内置了一些徽标可供更换$^*$。

\section{校徽}

\begin{tcbitemize}[raster rows=2, raster
    columns=3, raster every box/.style={
        center title,
        valign=center,
        halign=center,
        fonttitle=\ttfamily,
        colback=white}]
  \tcbitem[raster multicolumn=2,blankest]
  \begin{tcbitemize}[raster columns=2]
    \tcbitem[title={\cmd{zhlogo}}]
    \hbox{\resizebox{!}{1cm}{\zhlogo}}

    \tcbitem[title={\cmd{enlogo}}]
    \hbox{\resizebox{!}{1cm}{\enlogo}}

    \tcbitem[title={\cmd{sjtubadge}},height=3.5cm]
    \resizebox{!}{2cm}{\sjtubadge{}}

    \tcbitem[title={\cmd{dlogo}},height=3.5cm]
    \resizebox{3cm}{!}{\dlogo{}}
  \end{tcbitemize}
  \tcbitem[title={\cmd{vlogo}}]
  \resizebox{!}{4.8cm}{\vlogo{}}
\end{tcbitemize}

\beamerdemo[1]{step22.tex}

\begin{commentlist}
  \item 使用 \cmd{logo} 设定徽标。在主题处使用 \opt{topright}
  或 \opt{bottomright} 选项强制指定徽标的位置为右上角（\opt{max}
  默认）或左下角（\opt{maxplus} 和 \opt{min}）。
  \item 可以使用自定义的徽标，可以使用外部图片，
  或参见 \href{run:sjtubeamerdevguide.pdf}{开发指南}
  第 3.4 节创造可变颜色徽标$^*$。后者可以采用可选参数改变颜色，比如
  \cmd{zhlogo[cprimary]}。
\end{commentlist}

\section{二级机构组合}

也可以使用中文样式、英文样式与图片样式的二级机构组合。

\begin{tcbitemize}[raster rows=3,
    raster columns=1,
    raster every box/.style={
        center title,
        valign=center,
        halign=flush center,  % center 会导致额外的单词间距
        fonttitle=\ttfamily,
        colback=white}]

  \tcbitem[
    title={
        \cmd{secondaryinstlogo%
            [$\langle\textit{en}\rangle$]%
          \{$\langle\textit{zh}\rangle$\}%
          \{$\langle\textit{logo}\rangle$\}}}]
  \resizebox{!}{1cm}{\secondaryinstlogo
    [School of Mathematical Sciences]
    {数学科学学院}{\zhlogo{}}}

  \tcbitem[
    title={
        \cmd{secondaryinstlogo%
          \{$\langle\textit{en}\rangle$\}%
          \{$\langle\textit{logo}\rangle$\}}}]
  \resizebox{!}{1cm}{\secondaryinstlogo{School of
      Electronic, \\ Information and Electrical
      Engineering}{\enlogo{}}}

  \tcbitem[
    title={
        \cmd{secondaryinstlogo%
          \{\cmd{resizebox}\{!\}\{0.95cm\}%
          \{$\langle\textit{logo2}\rangle$\}\}%
          \{$\langle\textit{logo}\rangle$\}}}]
  \resizebox{!}{1cm}{\secondaryinstlogo{
      \resizebox{!}{0.95cm}
      {\includegraphics{sjtug.pdf}}}
    {\sjtubadge{}}}
\end{tcbitemize}

\begin{commentlist}
  \item 只有在不含可选参数的情况下（英文样式），可以在主要机构名中使用
  \textbackslash\textbackslash{} 对机构名进行换行。
  \item 注意与 \cmd{institute} 设置上的区别，非必要情况下最好直接使用
  \cmd{institute} 生成二级机构组合（比如 \opt{min} 样式的封面页）。
\end{commentlist}

\section{内置颜色}

建议在专用徽标或图表颜色上使用视觉形象系统规定的标准色，\themename{} 提供了这些内置颜色。

\begin{table}[h]
  \centering
  \small
  \begin{tabular}{llll}
    \hline
       & 主色                        & 二级色                         & 三级色                        \\
    红色 & \testclr{sjtuRedPrimary}  & \testclr{sjtuRedSecondary}  & \testclr{sjtuRedTertiary}  \\
    蓝色 & \testclr{sjtuBluePrimary} & \testclr{sjtuBlueSecondary} & \testclr{sjtuBlueTertiary} \\
    \hline
  \end{tabular}
\end{table}

\faInfoCircle{} 徽标与相关元素版权归上海交通大学所有，仅供学习交流使用。

\chapter{头图}

可以更改 \themename{} 封面中的头图。

\beamerdemo[1]{step23.tex}

\begin{commentlist}
  \item 使用 \cmd{titlegraphic} 设定头图，需要在封面图输出前进行赋值。
  \item 每个主题的头图位置不同，特别要注意默认的 \opt{max}
  主题的头图是淡色背景图。
  \item 对头图可以不设定大小，因为会自动填满占位符。
\end{commentlist}

\chapter{背景}

可以更改 \themename{} 的背景图。

\beamerdemo[1]{step24.tex}

\begin{commentlist}
  \item \cmd{setbeamertemplate\{background\}\{\}}
  可以设定背景图。如果设定为空，将会清除现在已经设定的背景图。请在主题加载完成后设定。
  \item \cmd{stamparray} 可以用于生成印记矩阵。$^*$
  \item \cmd{bgcenterbox} 命令可以用于居中背景图。$^*$
  \item 作为文字的背景，其透明度应该较低或者颜色偏淡。
\end{commentlist}

\chapter{自定}

\section{样式}

上面的自定义配置可以全部写入一个样式文件中，以在加载主题后加载这个自定义样式文件。采用
\texttt{my} 选项可以从零开始打造这些配置。

\beamerdemo[1]{step25.tex}

其中 \verb"\usepackage{my}" 即加载了同级目录下的
\verb"my.sty" 自定样式文件。

\examplecode{my.sty}

\begin{commentlist}
  \item 使用 \cmd{definecolor} 定义
  \opt{cprimary}、\opt{csecondary}$^*$ 可以改变主题颜色。
  \item 使用 \cmd{setbeamertemplate}
  可以直接设置对应的标题页、结束页、节次页等为已经定义的模板。
  \item 更多设置请参见
  \href{run:sjtubeamerdevguide.pdf}{开发文档}
  第 4.3 节。
\end{commentlist}

\section{插件}

从 GitHub 下载的社区版本中有插件可供使用，使用这些插件可以提高工作效率，减少寻找解决
方案的时间。

插件可以在
\href{https://github.com/sjtug/SJTUBeamer/issues/81}
{置顶的 Issue} 中浏览，使用下面的代码进行调用：
\examplecode{contrib.tex}

请注意，发布版和安装版不包含社区插件。如果希望贡献自己的插件，可以查看根目录下的
\verb"CONTRIBUTING.md"
以及\href{run:sjtubeamerdevguide.pdf}{开发文档}第1节。

%TODO: 未来的开发计划
%\chapter{字体}

\chapter{迁移}

\section{从 Markdown 或 \cls{article} 文档类迁移}

如果稿子已经预先使用 Markdown 或 \cls{article} 文档类完成，可以尝试使用
\href{https://logcreative.github.io/AutoBeamer/}{AutoBeamer}
幻灯片自动切分工具。这个方向迁移的关键在于充分利用 \cls{beamer} 提供的
\opt{allowframebreaks} 功能。

\section{迁移到其他主题}

上文中所有 \themename{} 独占的功能都已经用星号 $^*$
标记。在迁移到其他的主题时，您需要手动重定向这些独占命令。这些独占命令已经通过 VS Code
Snippets 的形式提供代码补全提示。

\begin{table}[h]
  \centering
  \begin{tabular}{ccc}
    \hline
    \cmd{makebottom}            &
    \env{bibliolist}            & \cmd{highlight}
    \\
    \cmd{paragraph}             & \env{codeblock}
                                &
    \cmd{stamparray}
    \\
    \cmd{*logo} \cmd{sjtubadge} &
    \cmd{stamphrule}            & \env{stampbox}
    \\
    \cmd{stamptext}             &
    \cmd{highlightline}         &
    \cmd{usesjtutheme}
    \\
    \hline
  \end{tabular}
\end{table}

并且需要补齐已经预先加载的宏包。

\begin{table}[h]
  \centering

  \begin{tabular}
    {>{\sffamily}c>{\sffamily}c>{\sffamily}c}
    \hline
    tikz & tcolorbox & array \\
    \hline
  \end{tabular}
\end{table}

我们更加推荐在本模板的基础上进行自定义修正来达到类似更换主题的效果
（比如高级操作部分提到的方法）。

关于 \themename{} 的讲座提供了一个
\href{https://github.com/sjtug/sjtulib-latex-talk/blob/logcreative-2022/beamerthemenosjtubeamer.sty}
{\cls{nosjtubeamer}}
主题用于将这些命令重定向到普通的样式上，修改该样式文件以满足迁移需求。

\chapter{贡献}

欢迎向 \themename{} 贡献您的代码！

\section{封面模板}

如果您通过内部的 \opt{my}
接口实现了自己的标题页和尾页模板，并且希望贡献到这个存储库让更多的人用到的话，欢迎进行
\href{https://github.com/sjtug/SJTUBeamer/pulls}{Pull Requests}
提供自己创建的主题。

为达成这一点，您可能需要
\begin{enumerate}
  \item 学习一些 Ti\textit{k}Z
        宏包的知识画出矢量图形。\texttt{texdoc pgf}
  \item 尝试通过
        \href{https://code.google.com/archive/p/tikzedt/downloads}{TikZEdt 编辑器} 打出草稿。
  \item 充分利用内部库 \texttt{sjtuvi} 来调用预先定义的视觉图案。
  \item 至少需要完成 16:9 和 4:3 的弹性布局，可能需要预先进行测试。
\end{enumerate}

\section{内核框架}

如果您是 \LaTeX{} 老手，欢迎向该框架提出您的改进、添加您的功能、优化其编译速度。
如果您暂时无法直接进行代码修改，可以先在
\href{https://github.com/sjtug/SJTUBeamer/issues}{Issues 区}
提出 Bug 反馈或功能提案。

为达成这一点，您可能需要
\begin{enumerate}
  \item 了解 \texttt{beamer}
        的 \href{https://latex-beamer.com/}{进阶操作}。
  \item 充分熟悉 \texttt{beamer}
        的结构与内部宏。\texttt{texdoc beamer}
  \item 阅读
        \href{run:sjtubeamerdevguide.pdf}{开发文档}，
        熟悉工程的构建方式与内部原理。
  \item 学习 \TeX{} 的
        \href{https://mirrors.sjtug.sjtu.edu.cn/CTAN/graphics/pgf/contrib/pgfplots/doc/TeX-programming-notes.pdf}{底层知识}。
  \item 尝试作出改动并通过回归测试、单元测试和集成测试。
\end{enumerate}

\chapter*{许可证}

\themename{} 符合
\href{https://github.com/sjtug/SJTUBeamer/blob/main/LICENSE}{Apache-2.0 开源许可}，不提供任何担保。

\texttt{sjtuvi} 和 \texttt{sjtucover}
库及其附属徽标、图片不符合上述开源许可，由上海交通大学持有
\href{https://vi.sjtu.edu.cn/index.php/articles/bulletin/16}{版权}。
校属各单位及个人以经营为目的使用视觉形象识别系统，须向学校申请使用许可。
校外单位及个人未经许可，不得制作或使用载有视觉形象识别系统的物品。

\vfill
{
\centering
\sjtuglogo\\
{\large \themename{}\\}
\today\\
}
\vfill

\end{document}
